<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <title>Db::key_range()</title>
    <link rel="stylesheet" href="apiReference.css" type="text/css" />
    <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
    <link rel="start" href="index.html" title="Berkeley DB C++ API Reference" />
    <link rel="up" href="db.html" title="Chapter 2.  The Db Handle" />
    <link rel="prev" href="dbjoin.html" title="Db::join()" />
    <link rel="next" href="dbopen.html" title="Db::open()" />
  </head>
  <body>
    <div xmlns="" class="navheader">
      <div class="libver">
        <p>Library Version 11.2.5.3</p>
      </div>
      <table width="100%" summary="Navigation header">
        <tr>
          <th colspan="3" align="center">Db::key_range()</th>
        </tr>
        <tr>
          <td width="20%" align="left"><a accesskey="p" href="dbjoin.html">Prev</a> </td>
          <th width="60%" align="center">Chapter 2. 
                The Db Handle
        </th>
          <td width="20%" align="right"> <a accesskey="n" href="dbopen.html">Next</a></td>
        </tr>
      </table>
      <hr />
    </div>
    <div class="sect1" lang="en" xml:lang="en">
      <div class="titlepage">
        <div>
          <div>
            <h2 class="title" style="clear: both"><a id="dbkey_range"></a>Db::key_range()</h2>
          </div>
        </div>
      </div>
      <pre class="programlisting">#include &lt;db_cxx.h&gt;
 
int
Db::key_range(DbTxn *txnid
    Dbt *key, DB_KEY_RANGE *key_range, u_int32_t flags);</pre>
      <p>
         The <code class="methodname">Db::key_range()</code> method returns an estimate of the proportion of
         keys that are less than, equal to, and greater than the specified key.
          The underlying database must be of type Btree.
    </p>
      <p>
         The <code class="methodname">Db::key_range()</code> method fills in a structure of type DB_KEY_RANGE.
          The following data fields are available from the DB_KEY_RANGE
         structure:
    </p>
      <div class="itemizedlist">
        <ul type="disc">
          <li>
            <p>
                          <span class="bold"><strong>double less;</strong></span>
                </p>
            <p>
                         A value between 0 and 1, the proportion of keys less than the
                         specified key.
                </p>
          </li>
          <li>
            <p>
                         <span class="bold"><strong>double equal;</strong></span>
                </p>
            <p>
                         A value between 0 and 1, the proportion of keys equal to the specified
                         key.
                </p>
          </li>
          <li>
            <p>
                         <span class="bold"><strong>double greater;</strong></span>
                </p>
            <p>
                         A value between 0 and 1, the proportion of keys greater than the
                         specified key.
                </p>
          </li>
        </ul>
      </div>
      <p>
         Values are in the range of 0 to 1; for example, if the field <span class="bold"><strong>less</strong></span> is 0.05, 5% of the keys in the database
         are less than the <span class="bold"><strong>key</strong></span> parameter.  The
         value for <span class="bold"><strong>equal</strong></span> will be zero if there
         is no matching key, and will be non-zero otherwise.
    </p>
      <p>
        The <code class="methodname">Db::key_range()</code> <span>
            
            <span>
                method either returns a non-zero error value or throws an
                exception that encapsulates a non-zero error value on
                failure, and returns 0 on success.
            </span>
        </span>
    </p>
      <div class="sect2" lang="en" xml:lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title"><a id="idp4348880"></a>Parameters</h3>
            </div>
          </div>
        </div>
        <div class="sect3" lang="en" xml:lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h4 class="title"><a id="idp4181136"></a>txnid</h4>
              </div>
            </div>
          </div>
          <p>
                          If the operation is part of an application-specified transaction, the
                          <span class="bold"><strong>txnid</strong></span> parameter is a transaction
                          handle returned from <a class="xref" href="txnbegin.html" title="DbEnv::txn_begin()">DbEnv::txn_begin()</a>; 
                          if the operation is part of a Berkeley DB Concurrent Data Store group, the
                          <span class="bold"><strong>txnid</strong></span> parameter is a handle returned
                          from <a class="xref" href="envcdsgroup_begin.html" title="DbEnv::cdsgroup_begin()">DbEnv::cdsgroup_begin()</a>;
                          otherwise NULL. If no transaction handle is specified, but the
                          operation occurs in a transactional database, the operation will be
                          implicitly transaction protected. The <code class="methodname">Db::key_range()</code> method does not
                          retain the locks it acquires for the life of the transaction, so
                          estimates may not be repeatable.
                     </p>
        </div>
        <div class="sect3" lang="en" xml:lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h4 class="title"><a id="idp2325976"></a>key</h4>
              </div>
            </div>
          </div>
          <p>
                          The key <a class="link" href="dbt.html" title="Chapter 4.  The Dbt Handle">Dbt</a>  operated on.
                     </p>
        </div>
        <div class="sect3" lang="en" xml:lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h4 class="title"><a id="idp954240"></a>key_range</h4>
              </div>
            </div>
          </div>
          <p>
                          The estimates are returned in the <span class="bold"><strong>key_range</strong></span> parameter, which contains three
                          elements of type double: <span class="bold"><strong>less</strong></span>,
                          <span class="bold"><strong>equal</strong></span>, and <span class="bold"><strong>greater</strong></span>.  Values are in the range of 0 to 1;
                          for example, if the field <span class="bold"><strong>less</strong></span> is
                          0.05, 5% of the keys in the database are less than the <span class="bold"><strong>key</strong></span> parameter.  The value for <span class="bold"><strong>equal</strong></span> will be zero if there is no matching key,
                          and will be non-zero otherwise.
                     </p>
        </div>
        <div class="sect3" lang="en" xml:lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h4 class="title"><a id="idp3709320"></a>flags</h4>
              </div>
            </div>
          </div>
          <p>
                          The <span class="bold"><strong>flags</strong></span> parameter is currently
                          unused, and must be set to 0.
                     </p>
        </div>
      </div>
      <div class="sect2" lang="en" xml:lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title"><a id="idp1564392"></a>Errors</h3>
            </div>
          </div>
        </div>
        <p>
                         The <code class="methodname">Db::key_range()</code> <span>
            
            <span>
                method may fail and throw a <a class="link" href="dbexception.html" title="Chapter 6. The DbException Class">DbException</a> 
                exception, encapsulating one of the following non-zero errors, or return one
                of the following non-zero errors:
            </span>
        </span>
                    </p>
        <div class="sect3" lang="en" xml:lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h4 class="title"><a id="idm181264"></a><span>DbDeadlockException or </span>DB_LOCK_DEADLOCK</h4>
              </div>
            </div>
          </div>
          <p>
                A transactional database environment operation was selected to resolve
                a deadlock.
            </p>
          <p>
                <a class="xref" href="dbdeadlock.html" title="DbDeadlockException">DbDeadlockException</a> is thrown if
                your Berkeley DB API is configured to throw exceptions.
                Otherwise, <code class="literal">DB_LOCK_DEADLOCK</code> is returned.
            </p>
        </div>
        <div class="sect3" lang="en" xml:lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h4 class="title"><a id="idm1852320"></a><span>DbLockNotGrantedException or </span>DB_LOCK_NOTGRANTED</h4>
              </div>
            </div>
          </div>
          <p>
                A Berkeley DB Concurrent Data Store database environment configured
                for lock timeouts was unable to grant a lock in the allowed time.
            </p>
          <p>
                You attempted to open a database handle that is configured
                for no waiting exclusive locking, but the exclusive lock could not be
                immediately obtained. See
                <a class="xref" href="dbset_lk_exclusive.html" title="Db::set_lk_exclusive()">Db::set_lk_exclusive()</a>
                for more information.
            </p>
          <p>
                <a class="xref" href="dblocknotgranted.html" title="DbLockNotGrantedException">DbLockNotGrantedException</a> is thrown if
                your Berkeley DB API is configured to throw exceptions.
                Otherwise, <code class="literal">DB_LOCK_NOTGRANTED</code> is returned.
            </p>
        </div>
        <div class="sect3" lang="en" xml:lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h4 class="title"><a id="idp3420832"></a> <span>DbRepHandleDeadException or</span> DB_REP_HANDLE_DEAD</h4>
              </div>
            </div>
          </div>
          <p>
                When a client synchronizes with the master, it is possible for committed
                transactions to be rolled back. This invalidates all  the database and cursor
                handles opened in the replication environment. Once this occurs, an attempt to use
                such a handle will 
                <span>
                    throw a <a class="xref" href="dbrephandledead.html" title="DbRepHandleDeadException">DbRepHandleDeadException</a> (if
                    your application is configured to throw exceptions), or 
                </span>
                return <code class="literal">DB_REP_HANDLE_DEAD</code>.
                The application will need to discard the handle and open a new one in order to
                continue processing.
            </p>
        </div>
        <div class="sect3" lang="en" xml:lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h4 class="title"><a id="idp1167312"></a><span>DbDeadlockException or </span>DB_REP_LOCKOUT</h4>
              </div>
            </div>
          </div>
          <p>
                The operation was blocked by client/master synchronization.
            </p>
          <p>
                <a class="xref" href="dbdeadlock.html" title="DbDeadlockException">DbDeadlockException</a> is thrown if
                your Berkeley DB API is configured to throw exceptions.
                Otherwise, <code class="literal">DB_REP_LOCKOUT</code> is returned.
            </p>
        </div>
        <div class="sect3" lang="en" xml:lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h4 class="title"><a id="idm607752"></a>EINVAL</h4>
              </div>
            </div>
          </div>
          <p>
                          If the underlying database was not of type Btree; or if an invalid
                          flag value or parameter was specified.
                        </p>
        </div>
      </div>
      <div class="sect2" lang="en" xml:lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title"><a id="idp4214024"></a>Class</h3>
            </div>
          </div>
        </div>
        <p>
                <a class="link" href="db.html" title="Chapter 2.  The Db Handle">Db</a>  
            </p>
      </div>
      <div class="sect2" lang="en" xml:lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title"><a id="idp1259904"></a>See Also</h3>
            </div>
          </div>
        </div>
        <p>
                     <a class="xref" href="db.html#dblist" title="Database and Related Methods">Database and Related Methods</a> 
                </p>
      </div>
    </div>
    <div class="navfooter">
      <hr />
      <table width="100%" summary="Navigation footer">
        <tr>
          <td width="40%" align="left"><a accesskey="p" href="dbjoin.html">Prev</a> </td>
          <td width="20%" align="center">
            <a accesskey="u" href="db.html">Up</a>
          </td>
          <td width="40%" align="right"> <a accesskey="n" href="dbopen.html">Next</a></td>
        </tr>
        <tr>
          <td width="40%" align="left" valign="top">Db::join() </td>
          <td width="20%" align="center">
            <a accesskey="h" href="index.html">Home</a>
          </td>
          <td width="40%" align="right" valign="top"> Db::open()</td>
        </tr>
      </table>
    </div>
  </body>
</html>
